<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Annotations for Field and Bean Properties of Resource Classes - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3"><a href="">Annotations for Field and Bean Properties of Resource Classes</a></p>
<p class="toc level4"><a href="#gkkya">Extracting Path Parameters</a></p>
<p class="toc level4"><a href="#gkkxj">Extracting Query Parameters</a></p>
<p class="toc level4"><a href="#gkkyc">Extracting Form Data</a></p>
<p class="toc level4"><a href="#gklcq">Extracting the Java Type of a Request or Response</a></p>
</div>
<p class="toc level3 tocsp"><a href="gknav.html">Subresources and Runtime Resource Resolution</a></p>
<p class="toc level4"><a href="gknav.html#gklag">Subresource Methods</a></p>
<p class="toc level4"><a href="gknav.html#gkrhr">Subresource Locators</a></p>
<p class="toc level3 tocsp"><a href="gkncy.html">Integrating JAX-RS with EJB Technology and CDI</a></p>
<p class="toc level3"><a href="gkqda.html">Conditional HTTP Requests</a></p>
<p class="toc level3"><a href="gkqbq.html">Runtime Content Negotiation</a></p>
<p class="toc level3"><a href="gkknj.html">Using JAX-RS With JAXB</a></p>
<p class="toc level2 tocsp"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="gjjxe.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="gknav.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gkkrb"></a><h2>Annotations for Field and Bean Properties of Resource Classes</h2>
<a name="indexterm-1271"></a><a name="indexterm-1272"></a><a name="indexterm-1273"></a><a name="indexterm-1274"></a><a name="indexterm-1275"></a><a name="indexterm-1276"></a><a name="indexterm-1277"></a><a name="indexterm-1278"></a><a name="indexterm-1279"></a><a name="indexterm-1280"></a><a name="indexterm-1281"></a><a name="indexterm-1282"></a><p>JAX-RS annotations for resource classes let you extract specific parts or values from
a Uniform Resource Identifier (URI) or request header.</p>

<p>JAX-RS provides the annotations listed in <a href="#gkobo">Table&nbsp;20-1</a>.</p>

<a name="gkobo"></a><p class="caption">Table&nbsp;20-1 Advanced JAX-RS Annotations</p><table><col width="50%"><col width="50%"><tr><th align="left" valign="top" scope="column"><p>Annotation</p>

</th>
<th align="left" valign="top" scope="column"><p>Description</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>@Context</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Injects information into a class field,
bean property, or method parameter</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>@CookieParam</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Extracts information from cookies declared in the cookie
request header</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>@FormParam</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Extracts information from a request representation whose content type is <tt>application/x-www-form-urlencoded</tt></p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>@HeaderParam</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Extracts the
value of a header</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>@MatrixParam</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Extracts the value of a URI matrix parameter</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>@PathParam</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Extracts the
value of a URI template parameter</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>@QueryParam</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Extracts the value of a URI query
parameter</p>

</td>
</tr>
</table>

<a name="gkkya"></a><h3>Extracting Path Parameters</h3>
<a name="indexterm-1283"></a><a name="indexterm-1284"></a><a name="indexterm-1285"></a><p>URI path templates are URIs with variables embedded within the URI syntax. The
<tt>@PathParam</tt> annotation lets you use variable URI path fragments when you call a
method. </p>

<p>The following code snippet shows how to extract the last name of
an employee when the employee's email address is provided:</p>

<pre>@Path(/employees/{"firstname}.{lastname}@{domain}.com")
public class EmpResource {

    @GET
    @Produces("text/xml")
    public String getEmployeelastname(@PathParam("lastname") String lastName) {
     ...
    }
}</pre><p>In this example, the <tt>@Path</tt> annotation defines the URI variables (or path parameters)
<tt>{firstname}</tt> , <tt>{lastname}</tt>, and <tt>{domain}</tt>. The <tt>@PathParam</tt> in the method parameter of the
request method extracts the last name from the email address. </p>

<p>If your HTTP request is GET <tt>/employees/john.doe@example.com</tt>, the value, &ldquo;<tt>doe</tt>&rdquo; is injected into
<tt>{lastname}</tt>.</p>

<p>You can specify several path parameters in one URI.</p>

<p>You can declare a regular expression with a URI variable. For example, if
it is required that the last name must only consist of lower
and upper case characters, you can declare the following regular expression:</p>

<pre>@Path(/employees/{"firstname}.{lastname[a-zA-Z]*}@{domain}.com")</pre><p>If the last name does not match the regular expression, a 404
response is returned.</p>



<a name="gkkxj"></a><h3>Extracting Query Parameters</h3>
<a name="indexterm-1286"></a><a name="indexterm-1287"></a><a name="indexterm-1288"></a><p>Use the <tt>@QueryParam</tt> annotation to extract query parameters from the query component of
the request URI.</p>

<p>For instance, to query all employees who have joined within a specific range
of years, use a method signature like the following:</p>

<pre>@Path(/employees/")
@GET
public Response getEmployees(
        @DefaultValue("2002") @QueryParam("minyear") int minyear,
        @DefaultValue("2010") @QueryParam("maxyear") int maxyear)
    {...}</pre><p>This code snippet defines two query parameters, <tt>minyear</tt> and <tt>maxyear</tt>. The following
HTTP request would query for all employees who have joined between 1999 and
2009:</p>

<pre>GET /employees?maxyear=2009&amp;minyear=1999</pre><p>The <tt>@DefaultValue</tt> annotation defines a default value, which is to be used if
no values are provided for the query parameters. By default, JAX-RS assigns a
null value for <tt>Object</tt> values and zero for primitive data types. You can
use the <tt>@DefaultValue</tt> annotation to eliminate null or zero values and define your
own default values for a parameter. </p>



<a name="gkkyc"></a><h3>Extracting Form Data</h3>
<a name="indexterm-1289"></a><a name="indexterm-1290"></a><a name="indexterm-1291"></a><p>Use the <tt>@FormParam</tt> annotation to extract form parameters from HTML forms. For example,
the following form accepts the name, address, and manager's name of an employee:</p>

<pre>&lt;FORM action="http://example.com/employees/" method="post">
&lt;p>
&lt;fieldset>
Employee name: &lt;INPUT type="text" name="empname" tabindex="1">  
Employee address: &lt;INPUT type="text" name="empaddress" tabindex="2"> 
Manager name: &lt;INPUT type="text" name="managername" tabindex="3"> 
&lt;/fieldset>
&lt;/p>
&lt;/FORM></pre><p>Use the following code snippet to extract the manager name from this HTML
form:</p>

<pre>@POST
@Consumes("application/x-www-form-urlencoded")
public void post(@FormParam("managername") String managername) {
    // Store the value
    ...
}</pre><p>To obtain a map of form parameter names to values, use a
code snippet like the following:</p>

<pre>@POST
@Consumes("application/x-www-form-urlencoded")
public void post(MultivaluedMap&lt;String. String> formParams) {
    // Store the message
}</pre>

<a name="gklcq"></a><h3>Extracting the Java Type of a Request or Response</h3>
<a name="indexterm-1292"></a><p>The <tt>javax.ws.rs.core.Context</tt> annotation retrieves the Java types related to a request or response.</p>

<p>The <tt>javax.ws.rs.core.UriInfo</tt> interface provides information about the components of a request URI. The
following code snippet shows how to obtain a map of query and path
parameter names to values:</p>

<pre>@GET
public String getParams(@Context UriInfo ui) {
    MultivaluedMap&lt;String, String> queryParams = ui.getQueryParameters();
    MultivaluedMap&lt;String, String> pathParams = ui.getPathParameters();
}</pre><p>The <tt>javax.ws.rs.core.HttpHeaders</tt> interface provides information about a request headers and cookies. The following
code snippet shows how to obtain a map of header and cookie parameter
names to values:</p>

<pre>@GET
public String getHeaders(@Context HttpHeaders hh) {
    MultivaluedMap&lt;String, String> headerParams = hh.getRequestHeaders();
    MultivaluedMap&lt;String, Cookie> pathParams = hh.getCookies();
}</pre>
         </div>
         <div class="navigation">
             <a href="gjjxe.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="gknav.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

